home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
QuickTime - The Beta Release
/
QuickTime - The Beta Release.iso
/
Programming Stuff
/
Interfaces
/
Oldstyle C Interfaces
/
PreviewComponent.h
< prev
next >
Wrap
Text File
|
1991-09-06
|
16KB
|
390 lines
/*
File: PreviewComponent.h
Written by: Chris Thorman
Copyright: © 1991 by Apple Computer, Inc., all rights reserved.
*/
#ifndef _PreviewComponentHeader_
#define _PreviewComponentHeader_
#include "Components.h" /* Components. */
#include "Image Compression.h" /* For ProgressProcPtr */
#include <StandardFile.h> /* For StandardFileReply.h */
/************************************************************************************
* *
* Thumbnail Resources *
* *
* Pre-computed preview information is stored in a document’s resource fork. *
* Typically, the information consists of a PRVL resource (ID = 0) which is *
* a list of other previewing-related resources found in the file. Normally, *
* the first (and usually, only) resource in the list is a PICT resource that *
* was created by the image compression manager. *
* *
* *
************************************************************************************/
typedef struct ResourceDesc {
ResType resourceType;
short resourceId;
};
typedef struct ResourceDesc ResourceDesc;
typedef struct ThumbnailList {
unsigned long date; /* When the resource was last modified. */
short version; /* Always 3 when using version shown here. */
ResType prevComponentType; /* The type of Preview Component that made the preview */
Str31 fileTypeDesc; /* Vernacular description of the type of the file */
short fileTypeDescScript; /* Script code for the file desc string */
short count; /* number of elements in the following array */
ResourceDesc resources[1]; /* an array of resource descriptions */
};
typedef struct ThumbnailList ThumbnailList;
typedef ThumbnailList * ThumbnailListPtr;
typedef ThumbnailListPtr * ThumbnailListHandle;
/************************************************************************************
* *
* Looking up Preview Components *
* *
* You will typically use preview components to add preview information to a *
* *
************************************************************************************/
/* The component type */
#define PreviewComponentType 'prvt'
/* The subtypes of the preview components provided by Apple */
#define FileInfoPrevCompSubType 'finf' /* Shows file type (from PRVL) and size */
#define PICTPrevCompSubType 'PICT' /* Creates / Shows PICT thumbnails */
#define MoviePrevCompSubType 'MooV' /* Creates thumbnails for movie files */
typedef ComponentInstance Previewer;
/* Preview Component Procedure Selectors */
enum {
prevComponentCreatePreviewRefNum = 2,
prevComponentGetPreviewData,
prevComponentAddPreviewRefNum = 5,
prevComponentStartPreviewing = 11,
prevComponentDoDraw,
prevComponentTimeSlice ,
prevComponentDoMouseDown,
prevComponentLastCall
};
/************************************************************************************
* *
* Using Preview Components to Create Previews *
* *
* You will typically use preview components to add preview information to a *
* document that your program has created. You’ll use the component manager to *
* get a component instance that matches the type of the preview that you want to *
* add (PICT or Movie are the only two currently supplied by Apple), then you’ll *
* call the CreatePreview routine if you want the component to create the preview *
* information and add it to the file, or AddPreview if you have already generated *
* the preview data and simply want it placed into the file (for instance, if you *
* have already created the thumbnail PICT and simply want it added.) *
* *
************************************************************************************/
/* Data structure used to specify the file type when creating a preview. TheString is
a string which the user will see when the preview appears in StandardFile. It
describes the file type in the vernacular (for example “Picture File”). scriptCode
is the script system to be used to display the string. Usually this will be the
system script. In any of the component calls that take a pointer to a
Str31WithScript structure, you may pass NIL and the
component will use its own string (localized) and script code.
Mainly, you will need to use this structure when adding a PICT preview to a
document that is not a PICT file, for instance, “MacWrite Document”, or “TeachText
Document”.
*/
struct Str31WithScript
{
Str31 theString;
short scriptCode;
};
typedef struct Str31WithScript Str31WithScript, *Str31WithScriptPtr, **Str31WithScriptHandle;
/* PreviewerCreatePreviewForResRefNum is called to create a preview for a file.
The file that you specify should be the same type as the preview component.
Use the Apple PICT component to create previews for PICT files.
Use the Apple Movie component to create previews for Movie files.
You do not have to call any of the other routines to use this one.
If removeOldPreviews is true, then any pre-existing preview data in the file will
be removed before the new preview is added. This includes any resources that
are listed in the PRVL resource, no matter which preview component put them there.
If removeOldPreviews is false, then the appropriate resources will be added to
the file and their description will be added to the end of the PRVL resource.
progressProc is a procedure that will be called periodically to indicate progress.
See the definition of ProgressProcPtr in the Image Compression Manager for details.
If fileTypeDescription is not 0, then the string and script code that it points to
will be placed into the thumbnail list that is created (in the fileTypeDesc and
fileTypeDescScript fields).
If the component opens the file’s data fork, it will be opened for read
access only.
The resRefNum argument is the reference number for the resource fork of the
file which has already been opened for write access.
*/
pascal ComponentResult
PreviewerCreatePreviewForResRefNum(Previewer p,
short resRefNum,
FSSpecPtr theFile,
Boolean removeOldPreviews,
Str31WithScriptPtr fileTypeDescription,
ProgressProcRecordPtr progressProc
)
= ComponentCallNow( prevComponentCreatePreviewRefNum, 16);
/* PreviewerGetPreviewData creates preview data for a file without actually adding
the data to the file or modifying the file in any way. The file is opened
read only.
The Handles passed in previewData and auxData should have already
been created in the application heap. Any data in them will be lost and
they will be resized as necessary. The caller is responsible for disposing them.
auxData is reserved for use by components that store their previews in
two chunks rather than one.
The type of the data depends on the type of the preview component. For
instance, the PICT preview component returns a picHandle to a thumbnail-sized
picture in previewData, and leaves auxData untouched.
*/
pascal ComponentResult
PreviewerGetPreviewData(Previewer p,
FSSpecPtr theFile,
Handle previewData,
Handle auxData,
ProgressProcRecordPtr progressProc
)
= ComponentCallNow( prevComponentGetPreviewData, 16);
/* PreviewerAddPreviewDataRefNum adds a preview that you have already created to a file.
It is called by a program that has already calculated a preview
for a file and simply wishes the data to be added to the file.
For instance, a program may create its own PICT thumbnail and then ask the PICT
previewer to add that to a file.
The type of the file does NOT have to match the type of the preview component.
Use this routine to add a PICT thumbnail to a file of any type,
such as a movie file or a text document.
This call should result in the data contained in the previewData handle being
added as a resource in the file’s resource fork. The type of the resource will
match the subtype of the preview component. For instance, the PICT component
adds PICTs. There is no way to specify a particular ID for the resource that
is added.
Different preview components may have slightly different behaviors in response
to this call. An extra argument, auxData, has been provided for components that
need to store two chunks of data. It is typically ignored. Currently, it is
ignored by the preview components provided by Apple.
You do not have to call any of the other routines to use this one.
If removeOldPreviews is true, then any pre-existing preview data in the file will
be removed before the new preview is added. This includes any resources that
are listed in the PRVL resource, no matter which preview component put them there.
If removeOldPreviews is false, then the appropriate resources will be added to
the file and their description will be added to the end of the PRVL resource.
progressProc is a procedure that will be called periodically to indicate progress.
See the definition of ProgressProcPtr in the Image Compression Manager for details.
If fileTypeDescription is not 0, then the string and script code that it points to
will be placed into the thumbnail list that is created (in the fileTypeDesc and
fileTypeDescScript fields).
This routine will not open the data fork of the file; the file does not even
need to have one.
The resRefNum argument is the reference number for the resource fork of the
file which has already been opened for write access.
*/
pascal ComponentResult
PreviewerAddPreviewDataRefNum(Previewer p,
short resRefNum,
FSSpecPtr theFile,
Boolean removeOldPreviews,
Str31WithScriptPtr fileTypeDescription,
Handle previewData,
Handle auxData
)
= ComponentCallNow( prevComponentAddPreviewRefNum, 20);
/************************************************************************************
* *
* Using Preview Components to Show Previews *
* *
* If your program needs to show previews, then you should use the component *
* routines described below. If you are writing a preview component, then you will *
* need to implement the appropriate routines so that the previews can be viewed in *
* StandardFile. *
* *
************************************************************************************/
/* This structure is the first argument to the following five component calls.
It describes the file that the component is being asked to show a preview for.
If the file has a resource fork, then it will be already have been opened for
read access and the refNum passed in the PreviewStatus record. If the file
had a thumbnail list (PRVL resource), then a resource handle to it will be
in PRVLHandle.
*/
struct PreviewStatusRec {
StandardFileReply fileInfo; /* See StandardFile.h */
long fileSize; /* File size in bytes */
short resRefNum; /* resource RefNum or 0 if no resource fork */
ThumbnailListHandle PRVLHandle; /* handle to the PRVL or 0 if none */
};
typedef struct PreviewStatusRec PreviewStatusRec, *PreviewStatusPtr, **PreviewStatusHandle;
/* PreviewerStartPreviewing is called to start previewing a file.
It may be called under two distinct circumstances:
1) when the file has a PRVL which was created by this component,
in which case the component will try to use its own pre-calculated
preview resources to show the preview, or
2) when the file’s type matches the type of the component,
in which case the component will either try to preview the file by
reading information directly from its data or resource forks or it
will return prevComponentCouldGeneratePreviewForThisFile, which means
that the component believes it could generate a preview for the file
if you were to call PreviewerCreatePreviewForFile.
If this routine returns noErr, then you MUST call PreviewerLastCall before
starting to preview a different file, creating a preview for a file, or closing
the preview component. If it returns any other value, then you should NOT
call PreviewerLastCall.
The component assumes that the grafPort specified in the window parameter is
the current grafport.
boundsRect describes the rectangle that can be used to show the preview in. Typically,
this is a 120x120 rectangle. Its coordinates are in terms of the current grafport.
If the component returns noErr, then it should set the coordinates of boundsRect
to be the rectangle which it is actually using to draw the preview in. The
modified boundsRect may be the same size as the original or smaller in any
dimension, but may not include any area outside the rectangle that was passed in.
If the component returns true in NeedInitialUpdate, then a DoDraw call
will be generated on the next time the window is updated (i.e. InvalRect will
be called). If false is returned in NeedInitialUpdate, then a DoDraw call
will only be called if the window needs updating during the normal course
of user actions (obscuring by another window, changing screen depth, etc.)
*/
pascal ComponentResult
PreviewerStartPreviewing(Previewer p,
PreviewStatusPtr status,
WindowPtr window,
Rect * boundsRect,
Boolean * NeedInitialUpdate
)
= ComponentCallNow( prevComponentStartPreviewing, 16 );
enum {
prevComponentCantPreviewThisFile = -9999,
prevComponentCouldGeneratePreviewForThisFile = -9998
};
/*
The following three routines are only called between successful calls
to the StartPreviewing and LastCall routines.
All drawing must stay within the boundsRect that was originally passed during
PreviewerStartPreviewing.
The grafport will be the same as during the StartPreviewing call.
*/
/* PreviewerDoDraw is called whenever the preview rectangle needs to be drawn.
*/
pascal ComponentResult
PreviewerDoDraw(Previewer p, PreviewStatusPtr status)
= ComponentCallNow( prevComponentDoDraw, 4 );
/* PreviewerDoMouseDown is called if the user clicks on the preview rectangle.
*/
pascal ComponentResult
PreviewerDoMouseDown(Previewer p, PreviewStatusPtr status)
= ComponentCallNow( prevComponentDoMouseDown, 4 );
/* PreviewerTimeSlice is called whenever there is idle time.
Use this routine to update temporal previews (such as sounds or animations).
If your component does not need time slice calls, it should return
prevComponentDontNeedTimeSlice when it is called.
*/
pascal ComponentResult
PreviewerTimeSlice(Previewer p, PreviewStatusPtr status)
= ComponentCallNow( prevComponentTimeSlice, 4 );
enum {
prevComponentDontNeedTimeSlice = -9993
};
/* PreviewerLastCall is called when it is time to stop previewing a file.
You can’t do any drawing during this call. You should free any resources
that you may have read in from the file and close the data fork of the file, if
you opened it during previewing.
This is not the same as the CloseComponent call — the component does not free
any of its internal storage, rather, it cleans up anything it allocated in order
to preview the current file. The component does not close the file’s resource
fork (stored in status->resRefNum), but it does close any other paths that
it opened during StartPreviewing.
*/
pascal ComponentResult
PreviewerLastCall(Previewer p, PreviewStatusPtr status)
= ComponentCallNow( prevComponentLastCall, 4 );
#endif _PreviewComponentHeader_